lib/emails/processAndSendEmail.ts (1)

37-38: Strengthen the JSDoc param description for maintainability

Good addition, but @param input is still too generic. Add a short description of expected fields (recipients/content/room context) so callers can understand usage without jumping to the interface definition.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/emails/processAndSendEmail.ts` around lines 37 - 38, Update the JSDoc for
the processAndSendEmail function to replace the generic "@param input" with a
brief description listing the expected fields (for example: recipients array,
content/body, subject, optional room or context identifier, and any metadata
like sender or attachments) so callers can understand what properties the input
object must contain without navigating to the interface; reference the parameter
name "input" and the function "processAndSendEmail" in the docblock and keep
descriptions one-line per field for clarity.

lib/catalog/getCatalogs.ts (1)

11-14: Improve JSDoc from stub to meaningful contract.

Nice addition, but the block is still a placeholder. Add a one-line function summary and a concrete @param accountId description so generated docs and IDE hints are useful.

Suggested JSDoc tweak

 /**
- *
- * `@param` accountId
+ * Fetches catalogs for the given account.
+ * `@param` accountId - Recoupable account identifier used as `account_id` query parameter.
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/catalog/getCatalogs.ts` around lines 11 - 14, Update the placeholder
JSDoc above the getCatalogs function to include a one-line summary describing
what getCatalogs does (e.g., "Retrieve available catalogs for an account") and a
concrete `@param` description for accountId (e.g., "accountId - unique identifier
of the account whose catalogs are being retrieved"). Ensure the block sits
immediately above the getCatalogs declaration and uses standard JSDoc tags so
IDEs and generated docs show the contract correctly.

lib/content/isCompletedRun.ts (1)

8-11: Make the JSDoc meaningful instead of a placeholder.

This stub satisfies linting but doesn’t add maintainability value. Please add a short summary and a descriptive @param (and optionally @returns) so intent is clear at call sites.

✍️ Suggested improvement

 /**
- *
- * `@param` run
+ * Returns true when a trigger run has reached COMPLETED status.
+ *
+ * `@param` run Trigger run payload containing status and metadata.
+ * `@returns` True if the run status is COMPLETED; otherwise false.
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/content/isCompletedRun.ts` around lines 8 - 11, Update the placeholder
JSDoc for the isCompletedRun function: replace the empty comment with a short
summary describing that isCompletedRun checks whether a run has reached a
terminal/completed state, add a descriptive `@param` for the run argument (e.g.,
"@param {Run} run - the run object to evaluate, including its status fields"),
and add a `@returns` tag (e.g., "@returns {boolean} true if the run is
completed/terminal, false otherwise") so callers understand intent and return
value; reference the isCompletedRun function name when making the change.

lib/content/contentTemplates.ts (1)

28-31: Complete the JSDoc contract (currently too skeletal).

Nice addition, but this block is effectively empty. Add a short function description, describe template, and include @returns so callers understand expected values quickly.

✍️ Suggested doc improvement

 /**
- *
- * `@param` template
+ * Checks whether a template name is one of the supported content templates.
+ *
+ * `@param` template - Template name to validate (e.g. "artist-caption-bedroom").
+ * `@returns` True when the template is supported; otherwise false.
  */
 export function isSupportedContentTemplate(template: string): boolean {
   return CONTENT_TEMPLATES.some(item => item.name === template);
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/content/contentTemplates.ts` around lines 28 - 31, Expand the skeletal
JSDoc above the function that accepts the parameter named "template" by adding a
one-line description of what the function does, a `@param` entry that describes
the "template" argument (include its expected type and shape or allowed values),
and an `@returns` entry that specifies the return type and what the return value
represents; update the JSDoc block for the function that references "template"
so callers can quickly see the behavior, input contract, and expected return
value.

lib/mcp/tools/transcribe/registerTranscribeAudioTool.ts (1)

18-21: Fill in the JSDoc stub with actual intent and parameter semantics.

The current block is effectively empty, so it doesn’t add much value for maintainers. A short summary + a concrete @param description would make this useful.

📝 Proposed JSDoc improvement

 /**
- *
- * `@param` server
+ * Registers the MCP tool that transcribes an audio URL and stores both
+ * the source audio file and generated transcript for the provided account.
+ *
+ * `@param` server MCP server instance where the `transcribe_audio` tool is registered.
  */
 export function registerTranscribeAudioTool(server: McpServer): void {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/transcribe/registerTranscribeAudioTool.ts` around lines 18 -
21, Replace the empty JSDoc stub above registerTranscribeAudioTool with a short
sentence describing its intent (e.g., "Registers audio transcription
endpoints/tools on the application server") and add a concrete `@param` entry for
the server parameter that specifies the expected type (the framework server
instance used in this codebase), what the function does with it (registers
routes/middleware or mutates state), and any required properties or lifecycle
expectations; also add an `@returns` tag if registerTranscribeAudioTool returns a
value (or use `@returns` {void} if it does not). Ensure the JSDoc mentions side
effects (route registration) and any thrown errors or async behavior so future
maintainers know how to call it.

lib/supabase/storage/uploadFileByKey.ts (1)

7-11: Make JSDoc actionable, not placeholder-only.

The new @param tags are present, but they should include concise descriptions (and ideally @returns/@throws) so this doc block is useful for maintainers, not just lint-compliant.

♻️ Suggested JSDoc improvement

 /**
  * Upload file to Supabase storage by key
  *
- * `@param` key
- * `@param` file
- * `@param` options
- * `@param` options.contentType
- * `@param` options.upsert
+ * `@param` key Storage object key/path inside the configured bucket.
+ * `@param` file File or Blob payload to upload.
+ * `@param` options Optional upload configuration.
+ * `@param` options.contentType MIME type used by Supabase Storage (defaults to application/octet-stream).
+ * `@param` options.upsert Whether to overwrite an existing object with the same key (default: false).
+ * `@returns` Resolves when upload completes successfully.
+ * `@throws` {Error} If Supabase returns an upload error.
  */

As per coding guidelines, lib/supabase/**/*.ts: "Supabase database functions should import from @/lib/supabase/serverClient and follow the documented pattern with JSDoc comments, error handling, and return types".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/supabase/storage/uploadFileByKey.ts` around lines 7 - 11, Update the
JSDoc for the uploadFileByKey function to be actionable: for each `@param` (key,
file, options, options.contentType, options.upsert) add a one-line description
including expected types (e.g., string for key, Buffer|Blob|Readable for file,
object for options), behavior (what contentType and upsert control), and any
defaults; add an `@returns` describing the Promise shape (e.g., Supabase upload
response or uploaded path) and an `@throws` indicating what errors are thrown
(e.g., upload failure, validation errors). Ensure the description follows the
repo pattern used by other Supabase helpers (brief purpose line at top),
mentions that it uses the server client, and matches the function name
uploadFileByKey so maintainers can quickly find and understand the contract.

lib/catalog/getCatalogSongs.ts (1)

28-34: Improve JSDoc with concrete parameter semantics.

Nice addition of docs. Please add short descriptions for each @param (and optionally @returns) so callers know expected ranges/default behavior (e.g., page is 1-based, default pageSize=100, artistName is a filter string).

✍️ Suggested doc refinement

 /**
- *
- * `@param` catalogId
- * `@param` pageSize
- * `@param` page
- * `@param` artistName
+ * Fetches a single page of songs from a catalog.
+ *
+ * `@param` catalogId Catalog identifier to query.
+ * `@param` pageSize Maximum songs per page (default: 100).
+ * `@param` page 1-based page number (default: 1).
+ * `@param` artistName Optional artist-name filter.
+ * `@returns` Catalog songs payload with pagination metadata.
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/catalog/getCatalogSongs.ts` around lines 28 - 34, Update the JSDoc for
the getCatalogSongs function to include short, concrete descriptions for each
parameter and the return: document that catalogId is the target catalog
identifier, page is 1-based (default 1), pageSize defaults to 100 and defines
max items per page, and artistName is an optional filter string used to match
artist names; also add a brief `@returns` description of the returned paginated
song list (including shape or that it may be empty). Reference the
getCatalogSongs function and its params (catalogId, pageSize, page, artistName)
when making these edits.

lib/admins/privy/getLatestVerifiedAt.ts (1)

7-8: ESLint fix applied successfully.

The @param user annotation satisfies the ESLint requirement. The function description is clear and the parameter is well-typed.

If you'd like to further enhance the documentation, consider adding a parameter description and a @returns annotation:

  *
- * `@param` user
+ * `@param` user - The Privy user object containing linked accounts to check
+ * `@returns` The most recent verification timestamp in milliseconds, or null if none found
  */

This is entirely optional—the current documentation is functional and meets the linting requirements.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/admins/privy/getLatestVerifiedAt.ts` around lines 7 - 8, Add a brief
description for the existing `@param` user and add a `@returns` annotation to the
JSDoc for the getLatestVerifiedAt function so the documentation is more
informative; update the block above function getLatestVerifiedAt to include
one-line text describing the user parameter and a `@returns` line describing the
returned value (e.g., a Date or null) while keeping types consistent with the
function signature.

lib/mcp/resolveAccountId.ts (1)

19-20: Consider adding descriptions to the nested parameter tags.

The auto-generated @param tags satisfy the linter, but they'd be more valuable with brief descriptions explaining what each parameter represents and when it's used.

📝 Suggested improvement for JSDoc clarity

  * `@param` params - The auth info and optional account_id override.
- * `@param` params.authInfo
- * `@param` params.accountIdOverride
+ * `@param` params.authInfo - Authentication info from the MCP API key (contains accountId if authenticated)
+ * `@param` params.accountIdOverride - Optional account_id to use instead of the authenticated account (requires access validation)
  * `@returns` The resolved accountId or an error message.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/resolveAccountId.ts` around lines 19 - 20, The JSDoc for
resolveAccountId.ts currently lists nested `@param` tags (params.authInfo,
params.accountIdOverride) with no descriptions; update the JSDoc for the
resolveAccountId function to add concise descriptions for each nested param
explaining what authInfo contains (e.g., credentials/token and its expected
shape) and when accountIdOverride is used (e.g., to force a specific account id
instead of deriving it), so readers and linters get meaningful documentation for
params.authInfo and params.accountIdOverride.

lib/catalog/formatCatalogSongsAsCSV.ts (1)

5-6: Consider completing the @param description for better documentation quality.

The @param tag was successfully added by the ESLint auto-fix, which is great progress. However, JSDoc best practices recommend including a description to explain the parameter's purpose.

📝 Suggested enhancement

 /**
  * Formats catalog songs into the CSV-like format expected by the scorer
  *
- * `@param` songs
+ * `@param` songs - Array of catalog songs to format as CSV
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/catalog/formatCatalogSongsAsCSV.ts` around lines 5 - 6, The JSDoc `@param`
for the songs parameter on formatCatalogSongsAsCSV is missing a description;
update the comment for the function formatCatalogSongsAsCSV to include a brief
description of the songs parameter (e.g., "songs — array of Song objects to
format as CSV" or similar, and optionally the expected element type like
Song[]), so the JSDoc clearly documents the parameter's purpose and type.

lib/chat/toolChains/getPrepareStepResult.ts (1)

18-73: Consider splitting function to stay under 50-line guideline.

The function spans 55 lines, slightly exceeding the coding guideline that recommends keeping functions under 50 lines. Consider extracting the sequence position finding logic (lines 30-43) or the result building logic (lines 48-69) into separate helper functions.

♻️ Example refactor to reduce function length

/**
 * Finds the current position in a tool sequence by matching against the execution timeline.
 */
const findSequencePosition = (
  executedTimeline: string[],
  fullSequence: Array<{ toolName: string }>,
  triggerIndex: number
): number => {
  let sequencePosition = 0;
  let timelinePosition = triggerIndex;

  while (timelinePosition < executedTimeline.length && sequencePosition < fullSequence.length) {
    const currentTool = executedTimeline[timelinePosition];
    const expectedTool = fullSequence[sequencePosition].toolName;

    if (currentTool === expectedTool) {
      sequencePosition++;
    }
    timelinePosition++;
  }

  return sequencePosition;
};

Then simplify the main function by calling const sequencePosition = findSequencePosition(executedTimeline, fullSequence, triggerIndex);

As per coding guidelines: "Keep functions under 50 lines" for functions in lib/**/*.ts.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/chat/toolChains/getPrepareStepResult.ts` around lines 18 - 73,
getPrepareStepResult is over the 50-line guideline; extract the
sequence-matching loop and the result-construction block into helpers to reduce
its size: create a findSequencePosition(executedTimeline, fullSequence,
triggerIndex) that returns sequencePosition (move lines ~30-43 there) and a
buildPrepareStepResult(nextToolItem, options) that builds and returns the
PrepareStepResult (move lines ~48-69 there), then call these helpers from
getPrepareStepResult to keep it concise and under 50 lines while preserving the
existing behavior and references to TOOL_CHAINS, TOOL_MODEL_MAP, and
getExecutedToolTimeline.

lib/supabase/files/createFileRecord.ts (1)

28-29: Consider adding a description to the @param annotation.

The @param params stub satisfies ESLint but could be more helpful with a brief description of the parameter's purpose.

📝 Optional enhancement for better documentation

 /**
  * Create a file record in the database
  *
- * `@param` params
+ * `@param` params - The file record parameters including account IDs, storage key, and metadata
  */

Or for more comprehensive documentation, you could document the object properties:

 /**
  * Create a file record in the database
  *
- * `@param` params
+ * `@param` params - The file record parameters
+ * `@param` params.ownerAccountId - Account ID of the file owner
+ * `@param` params.artistAccountId - Account ID of the associated artist
+ * `@param` params.storageKey - Storage key for the uploaded file
+ * `@param` params.fileName - Name of the file
+ * `@param` params.mimeType - MIME type of the file
+ * `@param` params.sizeBytes - Size of the file in bytes
+ * `@param` params.description - Optional description of the file
+ * `@param` params.tags - Optional tags for categorization
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/supabase/files/createFileRecord.ts` around lines 28 - 29, The JSDoc for
createFileRecord currently has a stubbed "@param params" entry; update the
comment for the createFileRecord function to describe what params represents
(e.g., an object containing file metadata like name, path, bucket, mimeType,
size, and any optional fields) or enumerate its properties (e.g., params.name,
params.path, params.bucket, params.mimeType, params.size) so readers and linters
get useful documentation; locate the createFileRecord function and replace the
"@param params" line with a concise description or a short list of param
properties.

lib/content/persistCreateContentRunVideo.ts (1)

33-127: Consider refactoring for Single Responsibility Principle.

This function handles multiple concerns: validation, database lookups, external fetching, storage uploads, record creation, race condition handling, and URL generation. At 95 lines, it exceeds the 50-line guideline. Consider extracting helper functions such as:

• downloadVideoFromUrl(url: string) for the fetch logic (lines 76-82)
• ensureFileRecord(params) for the create-or-select pattern (lines 91-107)
• buildVideoOutput(file, signedUrl) for constructing the output object (lines 64-71, 117-124)

This would improve testability and maintainability. As per coding guidelines, lib functions should keep functions under 50 lines and follow Single Responsibility Principle.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/content/persistCreateContentRunVideo.ts` around lines 33 - 127,
persistCreateContentRunVideo is doing too many things and should be split into
focused helpers; extract the fetch/download logic into
downloadVideoFromUrl(videoSourceUrl) to return a Blob and mimeType (replace
lines where fetch/response.blob/headers are used), extract the create-or-select
DB logic into ensureFileRecord({ownerAccountId, storageKey, fileName, mimeType,
sizeBytes, ...}) to encapsulate createFileRecord with the race-condition
re-select, and extract the output assembly into buildVideoOutput(fileRecord,
signedUrl) to produce the video output shape; update
persistCreateContentRunVideo to call these helpers in sequence (validate inputs,
call downloadVideoFromUrl, uploadFileByKey, call ensureFileRecord,
createSignedFileUrlByKey, then call buildVideoOutput) so behavior and error
handling remain identical but the main function stays under ~50 lines and each
concern is testable.

lib/github/expandSubmoduleEntries.ts (1)

14-22: JSDoc @param paths are inconsistent with the destructured function parameter.

The parameter object has three sibling properties (regularEntries, submoduleEntries, repo), but the docs incorrectly nest submoduleEntries and repo under regularEntries. Either use root0 for the parameter name and nest all properties under it (matching patterns in lib/evals/ and other files), or refactor the function signature to accept a named parameter (e.g., params) and document nested paths accordingly.

Suggested refactor

-export async function expandSubmoduleEntries({
+export async function expandSubmoduleEntries(params: {
   regularEntries,
   submoduleEntries,
   repo,
-}: {
   regularEntries: FileTreeEntry[];
   submoduleEntries: SubmoduleRef[];
   repo: { owner: string; repo: string; branch: string };
-}): Promise<FileTreeEntry[]> {
+}): Promise<FileTreeEntry[]> {
+  const { regularEntries, submoduleEntries, repo } = params;
   const submodules = await getRepoGitModules(repo);

Then update JSDoc:

 /**
  * Expands git submodule references into full directory trees.
  * Resolves submodule URLs from .gitmodules, fetches each submodule's tree,
  * and merges the results into the regular entries with correct path prefixes.
  *
- * `@param` regularEntries.regularEntries
- * `@param` regularEntries - Non-submodule file tree entries
- * `@param` submoduleEntries - Submodule references (type "commit" from GitHub Trees API)
- * `@param` repo - Repository context for fetching .gitmodules
- * `@param` regularEntries.submoduleEntries
- * `@param` regularEntries.repo
- * `@param` regularEntries.repo.owner
- * `@param` regularEntries.repo.repo
- * `@param` regularEntries.repo.branch
+ * `@param` params - Input payload
+ * `@param` params.regularEntries - Non-submodule file tree entries
+ * `@param` params.submoduleEntries - Submodule references (type "commit" from GitHub Trees API)
+ * `@param` params.repo - Repository context for fetching .gitmodules
+ * `@param` params.repo.owner - Repository owner
+ * `@param` params.repo.repo - Repository name
+ * `@param` params.repo.branch - Repository branch
  * `@returns` Combined file tree entries with submodules expanded as directories
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/github/expandSubmoduleEntries.ts` around lines 14 - 22, The JSDoc param
paths don't match the destructured parameter in expandSubmoduleEntries; update
the function signature docs to match the actual top-level parameter shape
(either change the function to accept a single named param like params/root0 and
document params.regularEntries, params.submoduleEntries, params.repo, or keep
the current destructured signature and document each top-level property with
`@param` regularEntries, `@param` submoduleEntries, `@param` repo and their
subproperties like `@param` repo.owner, `@param` repo.repo, `@param` repo.branch).
Ensure the names in the JSDoc exactly match the identifiers used in the function
(e.g., expandSubmoduleEntries's parameter names) so the docs are consistent.

lib/slack/getSlackUserInfo.ts (1)

19-21: Consider adding parameter descriptions to JSDoc.

The @param token and @param userId tags would be more helpful with descriptions.

📝 Suggested improvement

 /**
  * Fetches a Slack account's display name and avatar by their Slack ID.
  *
- * `@param` token
- * `@param` userId
+ * `@param` token - Slack bot authentication token
+ * `@param` userId - Slack user ID to look up
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/slack/getSlackUserInfo.ts` around lines 19 - 21, Add descriptive JSDoc
text for the function parameters in getSlackUserInfo: update the existing `@param`
token and `@param` userId tags to explain what each value is (e.g., token = Slack
API bearer token used for authentication; userId = Slack user ID whose profile
is being fetched) and include expected formats or constraints if any (string,
required, etc.) so future readers know how to call getSlackUserInfo.

lib/transcribe/saveTranscriptToFiles.ts (1)

5-8: Add function and parameter descriptions to JSDoc.

The JSDoc block lacks both a function description and parameter details.

📝 Suggested improvement

 /**
- *
- * `@param` params
+ * Uploads transcript markdown to storage and creates a file record.
+ *
+ * `@param` params - Transcript metadata including markdown content and account IDs
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/transcribe/saveTranscriptToFiles.ts` around lines 5 - 8, Add a clear
JSDoc summary for the saveTranscriptToFiles function and document its parameters
and return value: update the existing /** ... */ above saveTranscriptToFiles to
include a one-line description of what the function does, a `@param` block
describing the "params" object and each expected property (types and purpose),
and a `@returns/`@throws description if the function returns a value or can throw
errors; reference the saveTranscriptToFiles function and the params parameter by
name so future readers know what inputs and outputs to expect.

lib/slack/getBotChannels.ts (1)

12-13: Consider adding parameter description to JSDoc.

The @param token tag would be more useful with a description of what token is expected.

📝 Suggested improvement

 /**
  * Returns all channels the bot is a member of, paginating through all results.
  *
- * `@param` token
+ * `@param` token - Slack bot authentication token
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/slack/getBotChannels.ts` around lines 12 - 13, Update the JSDoc for the
getBotChannels function to add a clear description for the `@param` token tag:
explain what token represents (e.g., a Slack bot OAuth token or user token),
expected format (string), and any permissions/scopes required; locate the JSDoc
above the getBotChannels function in lib/slack/getBotChannels.ts and modify the
`@param` token line to include this information so callers know what to pass.

lib/transcribe/processAudioTranscription.ts (2)

10-11: Add parameter description to JSDoc.

The @param params tag would benefit from a description of what parameters are expected.

📝 Suggested improvement

 /**
  * Fetches audio from URL, transcribes it with OpenAI Whisper, and saves both
  * the original audio and transcript markdown to the customer's files.
  *
- * `@param` params
+ * `@param` params - Transcription parameters including audio URL, account IDs, and options
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/transcribe/processAudioTranscription.ts` around lines 10 - 11, The JSDoc
for processAudioTranscription is missing a description for the params parameter;
update the `@param` params tag to describe the expected object shape and fields
(e.g., audioBuffer or filePath, language, model, options like diarization or
timestamps, and any callback or logger) so callers know what to pass; modify the
JSDoc above the processAudioTranscription function to include a concise
description and list each expected property name/type and whether it is
required.

---

69-72: Add function and parameter descriptions to JSDoc.

The helper function's JSDoc block is incomplete with an empty description and no parameter details.

📝 Suggested improvement

 /**
- *
- * `@param` contentType
+ * Determines the appropriate file extension from a MIME content type.
+ *
+ * `@param` contentType - MIME type string (e.g., "audio/mp3", "audio/wav")
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/transcribe/processAudioTranscription.ts` around lines 69 - 72, The JSDoc
above the helper function is empty; add a short description of what the helper
does and document its parameter(s) and return value — specifically describe the
contentType parameter (expected MIME type string, allowed values, and how it's
used) and the function's return type/behavior; update the JSDoc block for the
helper function that accepts contentType so it contains `@param` {string}
contentType with a clear description and an `@returns` tag describing the return
value or side effects.

lib/transcribe/saveAudioToFiles.ts (1)

5-8: Add function and parameter descriptions to JSDoc.

The JSDoc block is incomplete with an empty description line and no parameter details. Adding context improves maintainability.

📝 Suggested improvement

 /**
- *
- * `@param` params
+ * Uploads audio blob to storage and creates a file record.
+ *
+ * `@param` params - Audio file metadata including blob, content type, and account IDs
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/transcribe/saveAudioToFiles.ts` around lines 5 - 8, Update the empty
JSDoc for the saveAudioToFiles function: provide a one-line description of what
saveAudioToFiles does, document each parameter passed in via the params object
(name, type and purpose — e.g., audioBuffer or stream, outputPath, fileName,
format, options), and add a `@returns` entry describing the resolved value or
Promise return (and any thrown errors). Reference the saveAudioToFiles function
and its params object so the JSDoc clearly explains inputs and outputs for
future maintainers.

lib/admins/privy/countNewAccounts.ts (1)

8-10: Consider adding parameter descriptions to JSDoc.

The @param users and @param period tags would benefit from brief descriptions explaining their purpose and expected values.

📝 Suggested improvement

 /**
  * Counts how many users in the list were created within the cutoff period.
  *
- * `@param` users
- * `@param` period
+ * `@param` users - Array of Privy user objects to filter
+ * `@param` period - Time period to check for account creation
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/admins/privy/countNewAccounts.ts` around lines 8 - 10, Update the JSDoc
for the countNewAccounts function to add brief descriptions for the `@param` tags:
describe what the users parameter expects (e.g., array of user objects or user
records and any required properties) and what the period parameter represents
(e.g., time window format such as number of days, start/end timestamps, or ISO
date range). Locate the JSDoc block immediately above the countNewAccounts
function and replace the placeholder `@param` users and `@param` period lines with
concise descriptions clarifying expected types and semantics.

lib/content/validateGetContentEstimateQuery.ts (1)

18-19: Consider adding parameter descriptions to JSDoc.

The @param request tag lacks a description. While the function-level comment is helpful, describing what the parameter represents improves documentation completeness.

📝 Suggested improvement

 /**
  * Validates auth and query params for GET /api/content/estimate.
  *
- * `@param` request
+ * `@param` request - The incoming Next.js request containing auth headers and query parameters
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/content/validateGetContentEstimateQuery.ts` around lines 18 - 19, Update
the JSDoc for the function validateGetContentEstimateQuery by expanding the
`@param request` tag to describe what the parameter represents (e.g., the
incoming query/request object for content estimate validation, including any
expected properties such as content type, length, or other fields used by
validateGetContentEstimateQuery). Keep the description concise and specific so
future readers know the shape/purpose of `request` when scanning the
validateGetContentEstimateQuery declaration.

lib/content/getArtistFileTree.ts (1)

7-9: Make @param docs explicit instead of placeholders.

The new JSDoc tags are currently empty, so they don’t help callers understand expected values/formats for githubRepo and artistSlug. Please add short, concrete descriptions.

Proposed doc-only improvement

 /**
  * Gets the file tree that contains the artist, checking the main repo
  * first, then falling back to org submodule repos.
  *
- * `@param` githubRepo
- * `@param` artistSlug
+ * `@param` githubRepo - Canonical GitHub repository URL (main sandbox repo).
+ * `@param` artistSlug - Artist folder slug to detect in repo paths.
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/content/getArtistFileTree.ts` around lines 7 - 9, The JSDoc for
getArtistFileTree currently has placeholder/empty `@param` tags for githubRepo and
artistSlug; update the comment above the getArtistFileTree function to replace
those placeholders with concise descriptions (e.g., githubRepo: full repository
identifier like "owner/repo" or a GitHub API repo object as expected by the
function; artistSlug: URL/filename-safe artist identifier used to locate the
artist's directory) so callers know the expected format and purpose of each
parameter.

lib/admins/privy/fetchPrivyLogins.ts (1)

23-26: Consolidate function docs; avoid split JSDoc blocks.

Right now the rich description is above FetchPrivyLoginsResult, and the function gets a near-empty stub. Move/merge the detailed docs to fetchPrivyLogins so documentation is attached to the correct symbol.

Proposed doc placement cleanup

-/**
- * Fetches Privy users active or created within the given period via the Privy Management API.
- * Returns the full, unmodified user objects from Privy.
- * Paginates through all users, collecting those whose created_at or latest_verified_at
- * falls within the time window.
- *
- * `@see` https://docs.privy.io/api-reference/users/get-all
- * `@param` period - "daily", "weekly", or "monthly"
- * `@returns` Array of full Privy user objects within the time window, sorted by created_at descending
- */
 export type FetchPrivyLoginsResult = {
   users: User[];
   totalPrivyUsers: number;
 };
 
 /**
- *
- * `@param` period
+ * Fetches Privy users active or created within the given period via the Privy Management API.
+ * Returns the full, unmodified user objects from Privy.
+ * Paginates through all users, collecting those whose created_at or latest_verified_at
+ * falls within the time window.
+ *
+ * `@see` https://docs.privy.io/api-reference/users/get-all
+ * `@param` period - "all", "daily", "weekly", or "monthly"
+ * `@returns` Full Privy users within the window, sorted by created_at descending, and total scanned count.
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/admins/privy/fetchPrivyLogins.ts` around lines 23 - 26, Merge the
separated JSDoc so the detailed description is attached to the actual function
symbol: remove the near-empty JSDoc block above FetchPrivyLoginsResult and
move/merge its rich documentation into the JSDoc immediately above the
fetchPrivyLogins function declaration; keep any parameter (`@param` period) and
return annotations consistent (referring to FetchPrivyLoginsResult where needed)
and ensure only fetchPrivyLogins carries the full descriptive comment so
generated docs link to the correct symbol.

app/api/admins/privy/route.ts (1)

18-20: Fill in the OPTIONS JSDoc body (currently empty).

The comment block is present, but adding a one-liner (preflight/CORS purpose) would make it useful to future maintainers.

Proposed doc-only improvement

 /**
- *
+ * OPTIONS /api/admins/privy
+ *
+ * Handles CORS preflight for the Privy admin endpoint.
  */
 export async function OPTIONS(): Promise<NextResponse> {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/admins/privy/route.ts` around lines 18 - 20, The empty JSDoc block
above the route handler should be replaced with a concise one-liner describing
its purpose—e.g., state that it handles CORS preflight/OPTIONS requests for the
admins/privy endpoint—so future maintainers know this is the OPTIONS (preflight)
handler; update the comment block in app/api/admins/privy/route.ts directly
above the route/handler definition to include that one-line description.

lib/content/getArtistContentReadiness.ts (1)

25-29: Replace root0.* JSDoc placeholders with meaningful argument docs.

The auto-generated root0 tags are hard to read. Please document the destructured object with explicit semantics for each field.

Proposed doc-only improvement

 /**
  * Checks whether an artist has the expected files for content creation.
  * Searches the main repo and org submodule repos.
  *
- * `@param` root0
- * `@param` root0.accountId
- * `@param` root0.artistAccountId
- * `@param` root0.artistSlug
+ * `@param` params - Input identifiers for readiness lookup.
+ * `@param` params.accountId - Account ID used to resolve sandbox snapshot metadata.
+ * `@param` params.artistAccountId - Artist account ID returned in the readiness response.
+ * `@param` params.artistSlug - Artist folder slug used to match content paths in GitHub.
  */
 export async function getArtistContentReadiness({

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/content/getArtistContentReadiness.ts` around lines 25 - 29, Update the
JSDoc for getArtistContentReadiness to replace the auto-generated root0
placeholders with meaningful parameter docs: document the function as taking a
single destructured params object (e.g., `@param` {Object} params) and add
explicit fields such as `@param` {string} params.accountId, `@param` {string}
params.artistAccountId, and `@param` {string} params.artistSlug (include types and
a short description for each) so readers can understand what each argument
represents; reference the getArtistContentReadiness function signature when
making these edits.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes